{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Labeling: Excess Return Over Mean\n",
    "\n",
    "![image_example](img/distribution_over_mean.png)\n",
    "_*Fig. 1:*_ Distribution of excess over mean return for 20 stock tickers from period between Jan 2019 and May 2020.\n",
    "\n",
    "## Abstract\n",
    "\n",
    "Using cross-sectional data on returns of many different stocks, each observation is labeled according to whether (or how much)\n",
    "its return exceeds the mean return. It is a common practice to label observations based on whether the return is positive or negative. However, this may produce unbalanced classes, as during market booms the probability of a positive return is much higher, and during market crashes they are lower (Coqueret and Guida, 2020). Labeling according to a benchmark such as mean return\n",
    "alleviates this issue.\n",
    "\n",
    "\n",
    "## How it works\n",
    "\n",
    "A dataframe containing forward total stock returns is calculated from close prices. The mean return of all companies at time $t$ in the dataframe is used to represent the market return, and excess returns are calculated by subtracting the mean return from each stock's return over the time period $t$. The numerical returns can then be used as-is (for regression analysis), or can be relabeled to represent their sign (for classification analysis).\n",
    "\n",
    "At time $t$:\n",
    "$$P_t = \\{p_{t,0}, p_{t,1}, ..., p_{t,n}\\}$$\n",
    "$$R_t = \\{r_{t,0}, r_{t,1}, ..., r_{t,n}\\}$$\n",
    "$$\\mu_t = mean(R_t)$$\n",
    "$$L(R_t) = \\{r_{t,0} - \\mu_t, r_{t,1} - \\mu_t, ...,r_{t,n} - \\mu_t\\}$$\n",
    "\n",
    "If categorical rather than numerical labels are desired:\n",
    "\n",
    "$$\n",
    "     \\begin{equation}\n",
    "     \\begin{split}\n",
    "       L(p_{t,n}) = \\begin{cases}\n",
    "       -1 &\\ \\text{if} \\ \\ r_{t,n} - \\mu_t < 0\\\\\n",
    "       0 &\\ \\text{if} \\ \\ r_{t,n} - \\mu_t = 0\\\\\n",
    "       1 &\\ \\text{if} \\ \\ r_{t,n} - \\mu_t > 0\\\\\n",
    "       \\end{cases}\n",
    "     \\end{split}\n",
    "     \\end{equation}\n",
    "$$\n",
    "\n",
    "---\n",
    "## Examples of use"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import pandas as pd\n",
    "import yfinance as yf\n",
    "\n",
    "from mlfinlab.labeling import excess_over_mean\n",
    "\n",
    "import matplotlib.pyplot as plt"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[*********************100%***********************]  20 of 20 completed\n"
     ]
    },
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>AMD</th>\n",
       "      <th>UBER</th>\n",
       "      <th>ZM</th>\n",
       "      <th>VZ</th>\n",
       "      <th>PFE</th>\n",
       "      <th>C</th>\n",
       "      <th>AAPL</th>\n",
       "      <th>FB</th>\n",
       "      <th>JPM</th>\n",
       "      <th>COST</th>\n",
       "      <th>GE</th>\n",
       "      <th>SYY</th>\n",
       "      <th>GOOG</th>\n",
       "      <th>UA</th>\n",
       "      <th>BABA</th>\n",
       "      <th>AAL</th>\n",
       "      <th>CCL</th>\n",
       "      <th>MSFT</th>\n",
       "      <th>WFC</th>\n",
       "      <th>F</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Date</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>2019-01-22</th>\n",
       "      <td>19.760000</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>54.096535</td>\n",
       "      <td>39.946537</td>\n",
       "      <td>59.116608</td>\n",
       "      <td>150.266403</td>\n",
       "      <td>147.570007</td>\n",
       "      <td>98.963676</td>\n",
       "      <td>209.413116</td>\n",
       "      <td>8.285392</td>\n",
       "      <td>60.661575</td>\n",
       "      <td>1070.520020</td>\n",
       "      <td>18.590000</td>\n",
       "      <td>152.149994</td>\n",
       "      <td>32.219025</td>\n",
       "      <td>51.750248</td>\n",
       "      <td>103.568062</td>\n",
       "      <td>46.484818</td>\n",
       "      <td>7.837517</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2019-01-23</th>\n",
       "      <td>19.799999</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>54.827435</td>\n",
       "      <td>39.842587</td>\n",
       "      <td>59.384232</td>\n",
       "      <td>150.874130</td>\n",
       "      <td>144.300003</td>\n",
       "      <td>98.713730</td>\n",
       "      <td>209.107468</td>\n",
       "      <td>8.352365</td>\n",
       "      <td>60.884239</td>\n",
       "      <td>1075.569946</td>\n",
       "      <td>18.400000</td>\n",
       "      <td>152.029999</td>\n",
       "      <td>31.146364</td>\n",
       "      <td>51.512947</td>\n",
       "      <td>104.577469</td>\n",
       "      <td>46.727222</td>\n",
       "      <td>7.689988</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2019-01-24</th>\n",
       "      <td>20.850000</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>54.172474</td>\n",
       "      <td>38.699097</td>\n",
       "      <td>59.938599</td>\n",
       "      <td>149.678253</td>\n",
       "      <td>145.830002</td>\n",
       "      <td>98.771400</td>\n",
       "      <td>207.352509</td>\n",
       "      <td>8.400200</td>\n",
       "      <td>60.535717</td>\n",
       "      <td>1073.900024</td>\n",
       "      <td>18.860001</td>\n",
       "      <td>155.860001</td>\n",
       "      <td>33.124386</td>\n",
       "      <td>52.224846</td>\n",
       "      <td>104.077667</td>\n",
       "      <td>46.596699</td>\n",
       "      <td>7.929724</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2019-01-25</th>\n",
       "      <td>21.930000</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>53.536488</td>\n",
       "      <td>38.406132</td>\n",
       "      <td>61.190701</td>\n",
       "      <td>154.638153</td>\n",
       "      <td>149.009995</td>\n",
       "      <td>99.396294</td>\n",
       "      <td>206.129929</td>\n",
       "      <td>8.763762</td>\n",
       "      <td>60.041988</td>\n",
       "      <td>1090.989990</td>\n",
       "      <td>19.490000</td>\n",
       "      <td>159.210007</td>\n",
       "      <td>34.423378</td>\n",
       "      <td>52.689953</td>\n",
       "      <td>105.028282</td>\n",
       "      <td>46.736546</td>\n",
       "      <td>8.169458</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2019-01-28</th>\n",
       "      <td>20.180000</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>52.274014</td>\n",
       "      <td>37.357147</td>\n",
       "      <td>61.028221</td>\n",
       "      <td>153.207047</td>\n",
       "      <td>147.470001</td>\n",
       "      <td>99.867378</td>\n",
       "      <td>207.806046</td>\n",
       "      <td>8.543714</td>\n",
       "      <td>60.284012</td>\n",
       "      <td>1070.079956</td>\n",
       "      <td>19.370001</td>\n",
       "      <td>158.919998</td>\n",
       "      <td>35.988075</td>\n",
       "      <td>53.534740</td>\n",
       "      <td>102.980049</td>\n",
       "      <td>46.447533</td>\n",
       "      <td>7.985046</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                  AMD  UBER  ZM         VZ        PFE          C        AAPL  \\\n",
       "Date                                                                           \n",
       "2019-01-22  19.760000   NaN NaN  54.096535  39.946537  59.116608  150.266403   \n",
       "2019-01-23  19.799999   NaN NaN  54.827435  39.842587  59.384232  150.874130   \n",
       "2019-01-24  20.850000   NaN NaN  54.172474  38.699097  59.938599  149.678253   \n",
       "2019-01-25  21.930000   NaN NaN  53.536488  38.406132  61.190701  154.638153   \n",
       "2019-01-28  20.180000   NaN NaN  52.274014  37.357147  61.028221  153.207047   \n",
       "\n",
       "                    FB        JPM        COST        GE        SYY  \\\n",
       "Date                                                                 \n",
       "2019-01-22  147.570007  98.963676  209.413116  8.285392  60.661575   \n",
       "2019-01-23  144.300003  98.713730  209.107468  8.352365  60.884239   \n",
       "2019-01-24  145.830002  98.771400  207.352509  8.400200  60.535717   \n",
       "2019-01-25  149.009995  99.396294  206.129929  8.763762  60.041988   \n",
       "2019-01-28  147.470001  99.867378  207.806046  8.543714  60.284012   \n",
       "\n",
       "                   GOOG         UA        BABA        AAL        CCL  \\\n",
       "Date                                                                   \n",
       "2019-01-22  1070.520020  18.590000  152.149994  32.219025  51.750248   \n",
       "2019-01-23  1075.569946  18.400000  152.029999  31.146364  51.512947   \n",
       "2019-01-24  1073.900024  18.860001  155.860001  33.124386  52.224846   \n",
       "2019-01-25  1090.989990  19.490000  159.210007  34.423378  52.689953   \n",
       "2019-01-28  1070.079956  19.370001  158.919998  35.988075  53.534740   \n",
       "\n",
       "                  MSFT        WFC         F  \n",
       "Date                                         \n",
       "2019-01-22  103.568062  46.484818  7.837517  \n",
       "2019-01-23  104.577469  46.727222  7.689988  \n",
       "2019-01-24  104.077667  46.596699  7.929724  \n",
       "2019-01-25  105.028282  46.736546  8.169458  \n",
       "2019-01-28  102.980049  46.447533  7.985046  "
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Load price data for 20 stocks\n",
    "tickers = \"AAPL GOOG MSFT COST PFE SYY F GE BABA AMD CCL ZM FB WFC JPM AAL UBER C UA VZ\"\n",
    "\n",
    "data = yf.download(tickers, start=\"2019-01-20\", end=\"2020-05-25\",\n",
    "                   group_by=\"ticker\")\n",
    "data = data.loc[:, (slice(None), 'Adj Close')]\n",
    "data.columns = data.columns.droplevel(1)\n",
    "data.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can find excess over mean over the given time period and plot the distribution."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>AMD</th>\n",
       "      <th>UBER</th>\n",
       "      <th>ZM</th>\n",
       "      <th>VZ</th>\n",
       "      <th>PFE</th>\n",
       "      <th>C</th>\n",
       "      <th>AAPL</th>\n",
       "      <th>FB</th>\n",
       "      <th>JPM</th>\n",
       "      <th>COST</th>\n",
       "      <th>GE</th>\n",
       "      <th>SYY</th>\n",
       "      <th>GOOG</th>\n",
       "      <th>UA</th>\n",
       "      <th>BABA</th>\n",
       "      <th>AAL</th>\n",
       "      <th>CCL</th>\n",
       "      <th>MSFT</th>\n",
       "      <th>WFC</th>\n",
       "      <th>F</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Date</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>2019-01-22</th>\n",
       "      <td>0.004297</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>0.015784</td>\n",
       "      <td>-0.000329</td>\n",
       "      <td>0.006800</td>\n",
       "      <td>0.006318</td>\n",
       "      <td>-0.019886</td>\n",
       "      <td>-0.000252</td>\n",
       "      <td>0.000814</td>\n",
       "      <td>0.010356</td>\n",
       "      <td>0.005944</td>\n",
       "      <td>0.006991</td>\n",
       "      <td>-0.007947</td>\n",
       "      <td>0.001485</td>\n",
       "      <td>-0.031020</td>\n",
       "      <td>-0.002312</td>\n",
       "      <td>0.012020</td>\n",
       "      <td>0.007488</td>\n",
       "      <td>-0.016550</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2019-01-23</th>\n",
       "      <td>0.043799</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>-0.021177</td>\n",
       "      <td>-0.037931</td>\n",
       "      <td>0.000104</td>\n",
       "      <td>-0.017157</td>\n",
       "      <td>0.001372</td>\n",
       "      <td>-0.008647</td>\n",
       "      <td>-0.017624</td>\n",
       "      <td>-0.003504</td>\n",
       "      <td>-0.014955</td>\n",
       "      <td>-0.010784</td>\n",
       "      <td>0.015769</td>\n",
       "      <td>0.015961</td>\n",
       "      <td>0.054276</td>\n",
       "      <td>0.004589</td>\n",
       "      <td>-0.014010</td>\n",
       "      <td>-0.012024</td>\n",
       "      <td>0.021944</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2019-01-24</th>\n",
       "      <td>0.034844</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>-0.028694</td>\n",
       "      <td>-0.024525</td>\n",
       "      <td>0.003936</td>\n",
       "      <td>0.016183</td>\n",
       "      <td>0.004852</td>\n",
       "      <td>-0.010628</td>\n",
       "      <td>-0.022850</td>\n",
       "      <td>0.026326</td>\n",
       "      <td>-0.025110</td>\n",
       "      <td>-0.001040</td>\n",
       "      <td>0.016450</td>\n",
       "      <td>0.004539</td>\n",
       "      <td>0.022261</td>\n",
       "      <td>-0.008048</td>\n",
       "      <td>-0.007821</td>\n",
       "      <td>-0.013953</td>\n",
       "      <td>0.013278</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2019-01-25</th>\n",
       "      <td>-0.070074</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>-0.013856</td>\n",
       "      <td>-0.017587</td>\n",
       "      <td>0.007070</td>\n",
       "      <td>0.000471</td>\n",
       "      <td>-0.000609</td>\n",
       "      <td>0.014465</td>\n",
       "      <td>0.017857</td>\n",
       "      <td>-0.015383</td>\n",
       "      <td>0.013757</td>\n",
       "      <td>-0.009440</td>\n",
       "      <td>0.003569</td>\n",
       "      <td>0.007904</td>\n",
       "      <td>0.055180</td>\n",
       "      <td>0.025759</td>\n",
       "      <td>-0.009776</td>\n",
       "      <td>0.003542</td>\n",
       "      <td>-0.012848</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2019-01-28</th>\n",
       "      <td>-0.037258</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>-0.023677</td>\n",
       "      <td>0.040195</td>\n",
       "      <td>-0.001197</td>\n",
       "      <td>-0.001538</td>\n",
       "      <td>-0.013415</td>\n",
       "      <td>0.011618</td>\n",
       "      <td>0.006644</td>\n",
       "      <td>0.005467</td>\n",
       "      <td>0.005294</td>\n",
       "      <td>-0.000014</td>\n",
       "      <td>-0.013889</td>\n",
       "      <td>-0.004010</td>\n",
       "      <td>0.001170</td>\n",
       "      <td>0.006344</td>\n",
       "      <td>-0.011539</td>\n",
       "      <td>0.009429</td>\n",
       "      <td>0.020374</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                 AMD  UBER  ZM        VZ       PFE         C      AAPL  \\\n",
       "Date                                                                     \n",
       "2019-01-22  0.004297   NaN NaN  0.015784 -0.000329  0.006800  0.006318   \n",
       "2019-01-23  0.043799   NaN NaN -0.021177 -0.037931  0.000104 -0.017157   \n",
       "2019-01-24  0.034844   NaN NaN -0.028694 -0.024525  0.003936  0.016183   \n",
       "2019-01-25 -0.070074   NaN NaN -0.013856 -0.017587  0.007070  0.000471   \n",
       "2019-01-28 -0.037258   NaN NaN -0.023677  0.040195 -0.001197 -0.001538   \n",
       "\n",
       "                  FB       JPM      COST        GE       SYY      GOOG  \\\n",
       "Date                                                                     \n",
       "2019-01-22 -0.019886 -0.000252  0.000814  0.010356  0.005944  0.006991   \n",
       "2019-01-23  0.001372 -0.008647 -0.017624 -0.003504 -0.014955 -0.010784   \n",
       "2019-01-24  0.004852 -0.010628 -0.022850  0.026326 -0.025110 -0.001040   \n",
       "2019-01-25 -0.000609  0.014465  0.017857 -0.015383  0.013757 -0.009440   \n",
       "2019-01-28 -0.013415  0.011618  0.006644  0.005467  0.005294 -0.000014   \n",
       "\n",
       "                  UA      BABA       AAL       CCL      MSFT       WFC  \\\n",
       "Date                                                                     \n",
       "2019-01-22 -0.007947  0.001485 -0.031020 -0.002312  0.012020  0.007488   \n",
       "2019-01-23  0.015769  0.015961  0.054276  0.004589 -0.014010 -0.012024   \n",
       "2019-01-24  0.016450  0.004539  0.022261 -0.008048 -0.007821 -0.013953   \n",
       "2019-01-25  0.003569  0.007904  0.055180  0.025759 -0.009776  0.003542   \n",
       "2019-01-28 -0.013889 -0.004010  0.001170  0.006344 -0.011539  0.009429   \n",
       "\n",
       "                   F  \n",
       "Date                  \n",
       "2019-01-22 -0.016550  \n",
       "2019-01-23  0.021944  \n",
       "2019-01-24  0.013278  \n",
       "2019-01-25 -0.012848  \n",
       "2019-01-28  0.020374  "
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "excess1 = excess_over_mean(data, lag=True)\n",
    "excess1.head()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAZYAAAEWCAYAAABFSLFOAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAALEgAACxIB0t1+/AAAADh0RVh0U29mdHdhcmUAbWF0cGxvdGxpYiB2ZXJzaW9uMy4yLjEsIGh0dHA6Ly9tYXRwbG90bGliLm9yZy+j8jraAAAgAElEQVR4nO3de5gcVZ3/8ffHhKuEmwkYkkAQI5qwXEcWr4uAgqIEdwXjDyUqbhYWZb2bqKu4azSuLqs8P0EDIgGVGBRIvKBAXMRVIA4CQrglmJAMCWRAAuGyAcJ3/zhnoNLp6emZqe7pTj6v5+lnqk9Vnfp2TXd9+5yqPqWIwMzMrCwvGuoAzMxs8+LEYmZmpXJiMTOzUjmxmJlZqZxYzMysVE4sZmZWKieWJpH0HUn/WlJde0p6XNKw/PxaSR8qo+5c35WSppZVXz+2+2VJD0l6oNnbtuaQ9E5JK/P796ChjmcoSLpQ0peHOo5GcmIpgaTlkp6StE7SWkl/kHSqpOf3b0ScGhH/XmddR9VaJiJWRMQOEbGhhNjPlPSDivrfGhFzBlt3P+MYB3wCmBgRL60y/3BJz+UD0jpJd0v6QJ11j5cUkoaXHXcf250oaYGkR3PM/y3ptU3c/rX5dR9QUX5FLj+8WbEUfAP4cH7/3jzYyiR9Q9KSvH/vknRyxfwDJd0k6cn898AadY2V9NP85eZRSbdJen+eNyTvoXblxFKed0TECGAvYBbwGeB7ZW9kM35j7wU8HBFraiyzKiJ2AHYEPgacJ2nfRgempF+fFUn7AL8HbgP2BvYALgeukvSaBsQ4rJdZ9wAnF5Z7CXAY0F12DHXaC1g8kBV7eY1PAO8AdgKmAt/qSd6StgbmAz8AdgHmAPNzeTUXAytzjC8h7bcHBxLrFi8i/BjkA1gOHFVRdijwHLBffn4h8OU8PRL4ObAW+CvwO1KSvziv8xTwOPBpYDwQwCnACuC6QtnwXN+1wFeBRcCjpA/Trnne4UBXtXiBY4CngWfy9m4t1PehPP0i4PPAfcAa4CJgpzyvJ46pObaHgM/V2E875fW7c32fz/UflV/zczmOC6usW+11rAFOKMQ5HbgXeBiYV9gHK3Kcj+fHa4AzgR8U6qq2T2eSksNTwMvz/FOBJcAjwLcB9fJaLwZ+WaX8XOC6PP0r0rf34vxbgb/P068Ers7vkbuBEwvLXZjr+iXp4HpUlW1dC3wB6AKG5bIP5/W6gMP72nd5/qXAA6T31nXApIo4vg38AlgH3AjsUyWWbfK+jxzvvbn8VTnOtaSEc1x/XmOV7SwAPpGn3wLcX/wf5ffCMb2s+zhwYC/zqr2Hev1s5HVeD/whv7aVwPurHAtGAP8NnA0IeBtwR96X9wOfHOrj20AeQx7A5vCgSmLJ5SuA0/J08c30VeA7wFb58YaeN39lXbxwwLsIeDGwHdUPgvcD++Vlfko+aFIjseTpMykcYAv19SSWDwJLgZcBOwCXARdXxHZejusAYD3wql7200WkpDcir3sPcEpvcVas+/z8/IE+jpSIDsplHwVuAMaSDmLfBS6piHN4ob6NXncv+3QFMAkYnv9PQfpCsDOwJylB9naQegD4QJXyNwEbgO1J34h/X5g3kXQQ2ib/H1cCH8jbP5iUuCcV3k+PAq/L+2PbKtu6FvgQcBXw1ly2iHRQLCaWXvdd4T0wIs/7JnBLYd6FpMR3aI7zh8DcGv/HAF6ep7civbc+C2wNHEE6oO5b72usqHs7YHXP/4TUqr2yYpmfkxNPlfWvIX2RmALsWTGv2nuo1mdjz/xa3pNf50vISSu/ri/nskXk40Ketxp4Q57eBTh4qI9vA3m4K6yxVgG7Vil/BhgN7BURz0TE7yK/k2o4MyKeiIinepl/cUTcHhFPAP8KnFije6Q/TgLOioi/RMTjwAxgSkWX3Jci4qmIuJX0jfuAykpyLO8GZkTEuohYDvwn8L5+xLKHpLWkFsTlwMfjhX76fyK1lroiYj0pcbxrkF2HF0bE4oh4NiKeyWWzImJtRKwgfdPsrc9+JOkgUWk16SC5S34NB0raK887Cbgsx/92YHlEfD9v/0+kLwzvKtQ1PyJ+HxHPRcT/1ngdFwEn527DnSPi+or5NfddRFyQ/2c98w6QtFNh/csiYlFEPEtKLL2ex6hwGOmAPCsino6I35AO/O8ZwGuE9GXtVuDX+fkOpMRU9CgpSVZzAqn34F+BZZJukfTqGtur9dk4CbgmIi7Jn/GHI+KWwrp7AL8FLo2IzxfKnwEmStoxIh7J//e248TSWGNI3+YqfZ30TecqSX+RNL2Oulb2Y/59pG9JI+uKsrY9cn3FuocDuxfKildxPUn6QFcaSfpWWlnXmH7EsioidiadYzmb9A23x17A5fniibXAnaSWwe6bVlO3avu8ntcKqXUxukr5aFJL65GIWEfqQpqS500hHZghvZ6/7Xk9+TWdBBQvbOjrPdHjMtK++gipi65Sr/tO0jBJsyTdK+kxUmsXNn5v1btPKu0BrIyI5wplle+Jul6jpK+TWuwnFr6kPU56rxTtSGpJbCIfyKdHxCTS++YW4ApJqhF/b5+NcaSuxd4cS2phfaei/B9I3WH3SfptI87HNYMTS4PkbzpjgP+pnJe//X0iIl5GOvH4cUlH9szupcq+WjTjCtN7kr75PETqm96+ENcwYFQ/6l1FOvAU636W/p/UfCjHVFnX/f2sh/zN+TPA30g6PhevJHX37Fx4bBsR91P9NW60X9j4gP38pvobW8E1pG/AlU4Ero+IJ/PzS4D35APIdqRWEKTX89uK17NDRJzW3/jytq4ETqN6Yqm17/4fMJl0HmwnUpcQpPMBg7UKGFdxYUTle6LP1yjpS8BbgbdExGOFWYuB/SsSw/7UcfFARDxEuoJtD1KvQ7U4an02VgL71NjEeaRzbL+U9OLCdv8YEZOB3YArSOe72o4TS8kk7Sjp7cBcUh/+bVWWebukl+c3/GOkb4c9lw4/SOqz7a/35stbtwf+DfhJpMuR7wG2lXSspK1IJxu3Kaz3IDC+xlVPlwAfk7S3pB2ArwA/zt0edcuxzANmShqRu38+Trpip98i4mlSV9oXctF3ct17AUgaJWlyntdNaiUU9+stwBuVfhO0E6kbo0xfAl4raaakXfNr/gjpvMpnCsv9knRw+jfSfu359v5z4BWS3idpq/x4taRXDTCezwJ/l7sgK9XadyNI580eJiXirwxw+9XcSErwn86v73DSF6259VYgaQYp+b05Ih6umH0t6XN1hqRtJH04l/+ml7q+Jmk/ScMljSAl4qW53mrvoVqfjR8CR0k6Mdf3kiqXOn+YdFHGzyVtJ2lrSSdJ2il3vfYcG9qOE0t5fiZpHembyueAs0gnXquZQPpG+zhwPXBORFyb530V+HzulvhkP7Z/Memk4APAtsAZABHxKPDPwPmkb4JPkE7c9rg0/31YUrX+3Aty3dcBy4D/JXWpDMRH8vb/QmrJ/SjXP1AXAHtKegfwLdIVQVfl/8MNwN/C89/YZwK/z/v1sIi4Gvgx8GfgJtKBvDQRsYR0VdABpO6j1aRujqMj4veF5daTuqqOIu2PnvJ1pKuappC+GT8AfI2NvxT0J55VEbFJ6znrdd+Rzs/cR3rv3JHnlSJ/OTiO1Np4CDgHODki7upHNV8htRSWKP3G6XFJny3Ufzwpma8lnWw/PpdXsz3pvNda0nt0rxxf1fcQNT4b+Rzc20i/zfor6YvMRucec5fdNNIxYz7pc/s+YHnudjwVeG8/9kXL6LkSyczMrBRusZiZWamcWMzMrFROLGZmVionFjMzK9XmOqAhI0eOjPHjxw91GGZmbeWmm256KCJG9b1k7zbbxDJ+/Hg6OzuHOgwzs7Yi6b6+l6rNXWFmZlYqJxYzMyuVE4uZmZXKicXMzErVsMQi6QJJayTdXlH+EaX7lS+W9B+F8hmSluZ5RxfKD1G69/RSSWfXGMLazMxaQCNbLBeSbn37PElvIg3BvX++58E3cvlE0mB7k/I65+iFm1SdSxqobUJ+bFSnmZm1loYlloi4jk1vcnUa6W5x6/Mya3L5ZNLtTNdHxDLSTbAOlTQa2DEirs8jgV5EGq3UzMxaVLPPsbwCeIOkG/Pd0Xpu+zmGje8U15XLxrDxEO895VVJmiapU1Jnd3d3yaGbmVk9mp1YhpPu9X0Y8ClgXj5nUu28SdQoryoiZkdER0R0jBo1qB+OmpnZADX7l/ddwGW5W2uRpOdI987uYuNb644l3dyoK09Xlpu1pfHTf1G1fPmsY5sciVnjNLvFcgVwBICkVwBbk+4ctwCYkm8fujfpJP2iiFgNrJN0WG7ZnEy605qZmbWohrVYJF0CHA6MlNQFfJF0K88L8iXITwNTc+tlsaR5pFufPgucnu+RDumE/4XAdsCV+WFmZi2qYYklIt7Ty6yq93COiJmke0pXlncC+5UYmpmZNZB/eW9mZqVyYjEzs1I5sZiZWamcWMzMrFROLGZmVionFjMzK5UTi5mZlcqJxczMSuXEYmZmpXJiMTOzUjmxmJlZqZxYzMysVE4sZmZWKicWMzMrlROLmZmVyonFzMxK5cRiZmalalhikXSBpDX5NsSV8z4pKSSNLJTNkLRU0t2Sji6UHyLptjzvbElqVMxmZjZ4jWyxXAgcU1koaRzwZmBFoWwiMAWYlNc5R9KwPPtcYBowIT82qdPMzFpHI+95f52k8VVm/RfwaWB+oWwyMDci1gPLJC0FDpW0HNgxIq4HkHQRcDxwZaPiNivD+Om/GOoQzIZMU8+xSDoOuD8ibq2YNQZYWXjelcvG5OnK8t7qnyapU1Jnd3d3SVGbmVl/NC2xSNoe+BzwhWqzq5RFjfKqImJ2RHRERMeoUaMGFqiZmQ1Kw7rCqtgH2Bu4NZ9/Hwv8SdKhpJbIuMKyY4FVuXxslXIzM2tRTWuxRMRtEbFbRIyPiPGkpHFwRDwALACmSNpG0t6kk/SLImI1sE7SYflqsJPZ+NyMmZm1mEZebnwJcD2wr6QuSaf0tmxELAbmAXcAvwJOj4gNefZpwPnAUuBefOLezKylNfKqsPf0MX98xfOZwMwqy3UC+5UanJmZNYx/eW9mZqVyYjEzs1I5sZiZWamcWMzMrFROLGZmVionFjMzK5UTi5mZlcqJxczMSuXEYmZmpXJiMTOzUjmxmJlZqZxYzMysVE4sZmZWKicWMzMrlROLmZmVyonFzMxK5cRiZmalauStiS+QtEbS7YWyr0u6S9KfJV0uaefCvBmSlkq6W9LRhfJDJN2W550tSY2K2czMBq+RLZYLgWMqyq4G9ouI/YF7gBkAkiYCU4BJeZ1zJA3L65wLTAMm5EdlnWZm1kIallgi4jrgrxVlV0XEs/npDcDYPD0ZmBsR6yNiGbAUOFTSaGDHiLg+IgK4CDi+UTGbmdngDeU5lg8CV+bpMcDKwryuXDYmT1eWVyVpmqROSZ3d3d0lh2tmZvUYksQi6XPAs8APe4qqLBY1yquKiNkR0RERHaNGjRp8oGZm1m/Dm71BSVOBtwNH5u4tSC2RcYXFxgKrcvnYKuVmZtaimtpikXQM8BnguIh4sjBrATBF0jaS9iadpF8UEauBdZIOy1eDnQzMb2bMZmbWPw1rsUi6BDgcGCmpC/gi6SqwbYCr81XDN0TEqRGxWNI84A5SF9npEbEhV3Ua6Qqz7UjnZK7EzMxaVsMSS0S8p0rx92osPxOYWaW8E9ivxNDMzKyB/Mt7MzMrlROLmZmVyonFzMxK5cRiZmalcmIxM7NSObGYmVmpnFjMzKxUTixmZlYqJxYzMyuVE4uZmZXKicXMzErlxGJmZqVyYjEzs1I5sZiZWamcWMzMrFROLGZmVionFjMzK1XDEoukCyStkXR7oWxXSVdLWpL/7lKYN0PSUkl3Szq6UH6IpNvyvLOV72lsZmatqZEtlguBYyrKpgMLI2ICsDA/R9JEYAowKa9zjqRheZ1zgWnAhPyorNPMzFpIXYlFUr/vOR8R1wF/rSieDMzJ03OA4wvlcyNifUQsA5YCh0oaDewYEddHRAAXFdYxM7MWVG+L5TuSFkn6Z0k7D2J7u0fEaoD8d7dcPgZYWViuK5eNydOV5VVJmiapU1Jnd3f3IMI0M7OBqiuxRMTrgZOAcUCnpB9JenOJcVQ7bxI1yquKiNkR0RERHaNGjSotODMzq1/d51giYgnweeAzwN8BZ0u6S9Lf92N7D+buLfLfNbm8i5S0eowFVuXysVXKzcysRdV7jmV/Sf8F3AkcAbwjIl6Vp/+rH9tbAEzN01OB+YXyKZK2kbQ36ST9otxdtk7SYflqsJML65iZWQsaXudy/x84D/hsRDzVUxgRqyR9vtoKki4BDgdGSuoCvgjMAuZJOgVYAZyQ61ksaR5wB/AscHpEbMhVnUa6wmw74Mr8MDOzFqV0sVUfC0k7AE/1HOwlvQjYNiKebHB8A9bR0RGdnZ1DHYZtocZP/0Up9SyfdWwp9ZjVS9JNEdExmDrqPcdyDanF0GP7XGZmZraRehPLthHxeM+TPL19Y0IyM7N2Vm9ieULSwT1PJB0CPFVjeTMz20LVe/L+o8Clknou9R0NvLsxIZmZWTurK7FExB8lvRLYl/Sjxbsi4pmGRmZmZm2p3hYLwKuB8XmdgyQRERc1JCozM2tbdSUWSRcD+wC3AD2/L+kZFNLMzOx59bZYOoCJUc+PXszMbItW71VhtwMvbWQgZma2eai3xTISuEPSImB9T2FEHNeQqMzMrG3Vm1jObGQQZma2+aj3cuPfStoLmBAR10jaHhjW13pmZrblqXfY/H8EfgJ8NxeNAa5oVFBmZta+6j15fzrwOuAxeP6mX7vVXMPMzLZI9SaW9RHxdM8TScOpcYtgMzPbctWbWH4r6bPAdvle95cCP2tcWGZm1q7qTSzTgW7gNuCfgF8CVe8caWZmW7a6EktEPBcR50XECRHxrjw94K4wSR+TtFjS7ZIukbStpF0lXS1pSf67S2H5GZKWSrpb0tED3a6ZmTVevVeFLZP0l8rHQDYoaQxwBtAREfuRLlueQmoVLYyICcDC/BxJE/P8ScAxwDmSfKmzmVmL6s9YYT22BU4Adh3kdreT9AzpTpSrgBnA4Xn+HOBa4DPAZGBuRKwHlklaChwKXD+I7ZuZWYPU2xX2cOFxf0R8EzhiIBuMiPuBbwArgNXAoxFxFbB7RKzOy6zmhcuZxwArC1V05bJNSJomqVNSZ3d390DCMzOzQap32PyDC09fRGrBjBjIBvO5k8nA3sBa0p0p31trlSplVc/vRMRsYDZAR0eHL4c2MxsC9XaF/Wdh+llgOXDiALd5FLAsIroBJF0GvBZ4UNLoiFgtaTSwJi/fBYwrrD+W1HVmZmYtqN6xwt5U4jZXAIfl8caeAo4EOoEngKnArPx3fl5+AfAjSWcBewATgEUlxmNmZiWqtyvs47XmR8RZ9W4wIm6U9BPgT6TWz82k7qsdgHmSTiElnxPy8oslzQPuyMufHhEbqlZuZmZDrj9Xhb2a1HoAeAdwHRufVK9bRHwR+GJF8XpS66Xa8jOBmQPZlpmZNVd/bvR1cESsA5B0JnBpRHyoUYGZtbrx038x1CGYtaR6h3TZE3i68PxpYHzp0ZiZWdurt8VyMbBI0uWkS33fCVzUsKjMzKxt1XtV2ExJVwJvyEUfiIibGxeWmZm1q3q7wiANvfJYRHwL6JK0d4NiMjOzNlbvIJRfJI3bNSMXbQX8oFFBmZlZ+6q3xfJO4DjSjxiJiFUMcEgXMzPbvNWbWJ7O918JAEkvblxIZmbWzupNLPMkfRfYWdI/AtcA5zUuLDMza1d9XhUmScCPgVcCjwH7Al+IiKsbHJuZmbWhPhNLRISkKyLiEMDJxMzMaqq3K+wGSa9uaCRmZrZZqPeX928CTpW0nHRlmEiNmf0bFZiZmbWnmolF0p4RsQJ4a5PiMTOzNtdXi+UK0qjG90n6aUT8QzOCMjOz9tXXOZbi/eZf1shAzMxs89BXYoleps3MzKrqK7EcIOkxSeuA/fP0Y5LWSXpsoBuVtLOkn0i6S9Kdkl4jaVdJV0takv/uUlh+hqSlku6WdPRAt2tmZo1XM7FExLCI2DEiRkTE8Dzd83zHQWz3W8CvIuKVwAHAncB0YGFETAAW5udImghMASYBxwDnSBo2iG2bmVkD9WfY/FJI2hF4I/A9gIh4OiLWApOBOXmxOcDxeXoyMDci1kfEMmApcGhzozYzs3o1PbGQLgLoBr4v6WZJ5+dBLXePiNUA+e9uefkxwMrC+l25bBOSpknqlNTZ3d3duFdgZma9GorEMhw4GDg3Ig4i/eByeo3lVaWs6oUEETE7IjoiomPUqFGDj9TMzPptKBJLF9AVETfm5z8hJZoHJY0GyH/XFJYfV1h/LLCqSbGamVk/NT2xRMQDwEpJ++aiI4E7gAXA1Fw2FZifpxcAUyRtk2+HPAFY1MSQzcysH+odK6xsHwF+KGlr4C/AB0hJbp6kU4AVwAkAEbFY0jxS8nkWOD0iNgxN2GZm1pchSSwRcQvQUWXWkb0sPxOY2dCgzMysFENxjsXMzDZjTixmZlYqJxYzMyuVE4uZmZXKicXMzErlxGJmZqVyYjEzs1I5sZiZWamcWMzMrFROLGZmVionFjMzK5UTi5mZlcqJxczMSuXEYmZmpXJiMTOzUg3Vjb7MrA7jp/+i13nLZx3bxEjM6ucWi5mZlWrIEoukYZJulvTz/HxXSVdLWpL/7lJYdoakpZLulnT0UMVsZmZ9G8oWy78AdxaeTwcWRsQEYGF+jqSJwBRgEnAMcI6kYU2O1czM6jQkiUXSWOBY4PxC8WRgTp6eAxxfKJ8bEesjYhmwFDi0WbGamVn/DFWL5ZvAp4HnCmW7R8RqgPx3t1w+BlhZWK4rl5mZWQtqemKR9HZgTUTcVO8qVcqil7qnSeqU1Nnd3T3gGM3MbOCGosXyOuA4ScuBucARkn4APChpNED+uyYv3wWMK6w/FlhVreKImB0RHRHRMWrUqEbFb2ZmNTQ9sUTEjIgYGxHjSSflfxMR7wUWAFPzYlOB+Xl6ATBF0jaS9gYmAIuaHLaZmdWplX4gOQuYJ+kUYAVwAkBELJY0D7gDeBY4PSI2DF2YZmZWy5Amloi4Frg2Tz8MHNnLcjOBmU0LzMzMBsy/vDczs1K1UleYWUuqNV6XmW3KLRYzMyuVE4uZmZXKicXMzErlxGJmZqVyYjEzs1I5sZiZWamcWMzMrFROLGZmVionFjMzK5UTi5mZlcqJxczMSuXEYmZmpXJiMTOzUjmxmJlZqZxYzMysVE4sZmZWqqbf6EvSOOAi4KXAc8DsiPiWpF2BHwPjgeXAiRHxSF5nBnAKsAE4IyJ+3ey4zVpNbzcgWz7r2CZHYraxoWixPAt8IiJeBRwGnC5pIjAdWBgRE4CF+Tl53hRgEnAMcI6kYUMQt5mZ1aHpiSUiVkfEn/L0OuBOYAwwGZiTF5sDHJ+nJwNzI2J9RCwDlgKHNjdqMzOr15CeY5E0HjgIuBHYPSJWQ0o+wG55sTHAysJqXbmsWn3TJHVK6uzu7m5U2GZmVkPTz7H0kLQD8FPgoxHxmKReF61SFtUWjIjZwGyAjo6OqsuY9aa3cxZm1j9D0mKRtBUpqfwwIi7LxQ9KGp3njwbW5PIuYFxh9bHAqmbFamZm/dP0xKLUNPkecGdEnFWYtQCYmqenAvML5VMkbSNpb2ACsKhZ8ZqZWf8MRVfY64D3AbdJuiWXfRaYBcyTdAqwAjgBICIWS5oH3EG6ouz0iNjQ/LDNzKweTU8sEfE/VD9vAnBkL+vMBGY2LCgzMyuNf3lvZmalcmIxM7NSObGYmVmpnFjMzKxUTixmZlaqIfvlvZk1hkc9tqHmxGJbFA/bYtZ47gozM7NSObGYmVmpnFjMzKxUTixmZlYqn7w320LUunDBV4xZmZxYbLPkq7/Mho67wszMrFRusZhZv1t47jqzWpxYrK25y8us9bgrzMzMStU2LRZJxwDfAoYB50fErCEOyUrm1kf7GMj/yt1nW462SCyShgHfBt4MdAF/lLQgIu4Y2si2HGX2wTuBbJnKHBzTA222NkXEUMfQJ0mvAc6MiKPz8xkAEfHV3tbp6OiIzs7OJkXYXnxgN3uBk9HGJN0UER2DqaMtWizAGGBl4XkX8LeVC0maBkzLT9dLur0JsQ3WSOChoQ6iD+0QIzjOsm0RceprJUZSW7vsz30HW0G7JBZVKdukqRURs4HZAJI6B5t1m6Ed4myHGMFxls1xlqud4hxsHe1yVVgXMK7wfCywaohiMTOzGtolsfwRmCBpb0lbA1OABUMck5mZVdEWXWER8aykDwO/Jl1ufEFELO5jtdmNj6wU7RBnO8QIjrNsjrNcW0ycbXFVmJmZtY926QozM7M24cRiZmalatvEImlXSVdLWpL/7lJlmXGS/lvSnZIWS/qX/qzfrDjzchdIWlP52xtJZ0q6X9It+fG2Fo2z1fbnMZLulrRU0vRCeUP3Z2/bLcyXpLPz/D9LOrjedVskxuWSbsv7rqG/QK4jzldKul7Sekmf7M+6LRRnK+3Pk/L/+8+S/iDpgHrX3UREtOUD+A9gep6eDnytyjKjgYPz9AjgHmBives3K848743AwcDtFeVnAp9shf3ZR5wtsz9JF3jcC7wM2Bq4tfB/b9j+rLXdwjJvA64k/TbrMODGetcd6hjzvOXAyCa8H+uJczfg1cDM4v+0WftysHG24P58LbBLnn7rYN6bbdtiASYDc/L0HOD4ygUiYnVE/ClPrwPuJP2Kv671mxVnju864K8NiqEeg42zlfbnocDSiPhLRDwNzM3rNVo9250MXBTJDcDOkkY3MebBxNhMfcYZEWsi4o/AM/1dt0XibKZ64vxDRDySn95A+r1gXetWaufEsntErIaUQEjfCnolaTxwEHDjQNZvVpy9+HBunl7QqC4mBh9nK+3PakMAjSk8b9T+7Gu7tZapZ92hjhHSiBdXSbpJaQilRhnM/mjWvixjW626P08htVoHsm5r/45F0jXAS6vM+lw/69kB+Cnw0Yh4rIzYKuovJc5enAv8O+kN+KMTxO8AAAVySURBVO/AfwIfHEhFDY6zNCXEWWsIoNL2Zz+329cydQ1bVILBxAjwuohYJWk34GpJd+VWbNkGsz+atS/L2FbL7U9JbyIlltf3d90eLZ1YIuKo3uZJelDS6IhYnZvpa3pZbitSUvlhRFxWmFXX+s2Ks0bdDxbqOg/4eSvGSWvtz16HACpzf/Znu3Uss3Ud6w51jEREz981ki4ndZM04kA4mGGcmjkE1KC21Wr7U9L+wPnAWyPi4f6sW9TOXWELgKl5eiowv3IBSQK+B9wZEWf1d/1mxVlLRd/2O4FGjdg82P3RSvuz1yGAGrw/6xl6aAFwcr7y6jDg0dyl16xhiwYco6QXSxoBIOnFwFto3PtxMPujmUNADXhbrbY/Je0JXAa8LyLu6c+6m2j01QiNegAvARYCS/LfXXP5HsAv8/TrSU22PwO35Mfbaq0/FHHm55cAq0kn+LqAU3L5xcBt+TUsAEa3aJyttj/fRroK8F7gc4Xyhu7PatsFTgVOzdMi3bTu3hxHR18xN2AfDihG0lVBt+bH4kbGWGecL83vwceAtXl6x2buy8HE2YL783zgEV44VnYO9L3pIV3MzKxU7dwVZmZmLciJxczMSuXEYmZmpXJiMTOzUjmxmJlZqZxYrO1J2pBHh71d0s8k7dzH8sdLmtjAeLaW9E1J9yqNwjxf0ti+1xzQtq6VtCL/Zqun7ApJjzdie2b1cGKxzcFTEXFgROxHGiDz9D6WPx7oV2KR1J9RKr5CGk37FRExAbgCuKx48B+I/IPFap/ZtcDr8jI7k0b1NhsyTiy2ubmePECepH0k/SoP8Pc7pftivBY4Dvh6buXsk7/1d+R1RkpanqffL+lSST8jDRT4fkmX5TqXSPqPyo1L2h74APCxiNgAEBHfB9YDR0j6mqR/Lix/pqRP5OlPSfqj0gCZX8pl45XuJ3QO8Cc2Hlqjx1zSr6EB/p706+liTJvUm8uvyPtmsQoDIEp6XNJMSbdKukHS7nXvfTOcWGwzImkYcCQvDDcxG/hIRBwCfBI4JyL+kOd/Krdy7u2j2tcAUyPiiPz8QODdwN8A75ZUeaB/ObAiNh3stBOYREoC7y6UnwhcKuktwATSWFEHAodIemNeZl/SMPYHRcR9VWJcCLwxv/4pwI8L+6RWvR/M+6YDOEPSS3L5i4EbIuIA0rhV/9j77jHbVEsPQmlWp+0k3QKMB24ijRK7A+nGRZcWeqC2GUDdV0dE8f4zCyPiUQBJdwB7sfGQ4qL6yK8CIiJulrSbpD2AUcAjEbFC0hmksaJuzsvvQEoIK4D7It0XpTcbgP8hJaztImJ54TW/pZd6ryMlk3fm8nG5/GHgaV4YnPMm4M01tm22CScW2xw8FREHStqJdEA8HbgQWBsRB9ax/rO80HrftmLeExXP1xemN7DpZ2gpsJekEZFuLtfjYOBnefonwLtIY0jNzWUCvhoR3y1WpnQfocoYqpkLXE66Q+ZGVfRS7+HAUcBrIuJJSdfywmt/Jl4Y66naazSryV1httnILYkzSN1eTwHLJJ0Az5/47rmH9zrSyfUey4FD8vS7BhnDE6Q7W56Vu6aQdDKwPfCbvFjPOZF3kZIMwK+BD+aWFpLGKN2jo16/A75KGiS0qLd6dyK1lp6U9ErSLYjNSuHEYpuViLiZNFrsFOAk4BRJPaPH9txOdS7wKUk3S9oH+AZwmqQ/ACNLCGMG8L/APZKWACcA7+xpBUTEYlJiuz9euBvmVcCPgOsl3UZKOCOqVV5NJN+IiIcqynur91fAcEl/Jt3wrFZXm1m/eHRjMzMrlVssZmZWKicWMzMrlROLmZmVyonFzMxK5cRiZmalcmIxM7NSObGYmVmp/g+a/Mcnt42KXQAAAABJRU5ErkJggg==\n",
      "text/plain": [
       "<Figure size 432x288 with 1 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "s1 = pd.Series(excess1.iloc[:-1, :].values.flatten())\n",
    "ax1 = s1.plot.hist(bins=80)\n",
    "ax1.set_xlim(-0.2,0.2)\n",
    "ax1.set_xlabel('Return Over Mean')\n",
    "ax1.set_title('Distribution of Return Over Mean for 20 Stocks'); "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can return the sign of the excess over mean rather than the numerical value."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "-1.0    3347\n",
       " 1.0    3256\n",
       "dtype: int64"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "excess2 = excess_over_mean(data, binary=True)\n",
    "excess2.stack().value_counts()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## With resampling"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also resample data prior to labeling."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>AMD</th>\n",
       "      <th>UBER</th>\n",
       "      <th>ZM</th>\n",
       "      <th>VZ</th>\n",
       "      <th>PFE</th>\n",
       "      <th>C</th>\n",
       "      <th>AAPL</th>\n",
       "      <th>FB</th>\n",
       "      <th>JPM</th>\n",
       "      <th>COST</th>\n",
       "      <th>GE</th>\n",
       "      <th>SYY</th>\n",
       "      <th>GOOG</th>\n",
       "      <th>UA</th>\n",
       "      <th>BABA</th>\n",
       "      <th>AAL</th>\n",
       "      <th>CCL</th>\n",
       "      <th>MSFT</th>\n",
       "      <th>WFC</th>\n",
       "      <th>F</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Date</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>2019-01-27</th>\n",
       "      <td>0.088544</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>-0.061905</td>\n",
       "      <td>0.035230</td>\n",
       "      <td>-0.027578</td>\n",
       "      <td>0.026424</td>\n",
       "      <td>0.082970</td>\n",
       "      <td>-0.024364</td>\n",
       "      <td>-0.023363</td>\n",
       "      <td>0.083342</td>\n",
       "      <td>-0.004111</td>\n",
       "      <td>-0.010991</td>\n",
       "      <td>-0.061427</td>\n",
       "      <td>0.025918</td>\n",
       "      <td>0.003201</td>\n",
       "      <td>0.010529</td>\n",
       "      <td>-0.070066</td>\n",
       "      <td>-0.044595</td>\n",
       "      <td>-0.027758</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2019-02-03</th>\n",
       "      <td>-0.050317</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>-0.001748</td>\n",
       "      <td>-0.005908</td>\n",
       "      <td>-0.016821</td>\n",
       "      <td>0.037000</td>\n",
       "      <td>0.019027</td>\n",
       "      <td>-0.015008</td>\n",
       "      <td>-0.000065</td>\n",
       "      <td>-0.028041</td>\n",
       "      <td>0.050622</td>\n",
       "      <td>-0.004875</td>\n",
       "      <td>0.018795</td>\n",
       "      <td>0.005619</td>\n",
       "      <td>0.008922</td>\n",
       "      <td>-0.009464</td>\n",
       "      <td>0.037369</td>\n",
       "      <td>-0.016511</td>\n",
       "      <td>-0.028594</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2019-02-10</th>\n",
       "      <td>0.012733</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>0.007829</td>\n",
       "      <td>-0.010573</td>\n",
       "      <td>0.021847</td>\n",
       "      <td>-0.014540</td>\n",
       "      <td>-0.043464</td>\n",
       "      <td>0.026739</td>\n",
       "      <td>0.027374</td>\n",
       "      <td>0.013943</td>\n",
       "      <td>0.005643</td>\n",
       "      <td>0.002377</td>\n",
       "      <td>-0.014599</td>\n",
       "      <td>-0.021829</td>\n",
       "      <td>-0.040988</td>\n",
       "      <td>-0.003651</td>\n",
       "      <td>0.009532</td>\n",
       "      <td>0.018349</td>\n",
       "      <td>0.003279</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2019-02-17</th>\n",
       "      <td>0.013680</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>0.016871</td>\n",
       "      <td>-0.001829</td>\n",
       "      <td>-0.017059</td>\n",
       "      <td>-0.000073</td>\n",
       "      <td>-0.018790</td>\n",
       "      <td>-0.020247</td>\n",
       "      <td>-0.015868</td>\n",
       "      <td>-0.007107</td>\n",
       "      <td>-0.018145</td>\n",
       "      <td>-0.017981</td>\n",
       "      <td>0.017527</td>\n",
       "      <td>0.049785</td>\n",
       "      <td>-0.002482</td>\n",
       "      <td>0.021192</td>\n",
       "      <td>0.014754</td>\n",
       "      <td>-0.019099</td>\n",
       "      <td>0.004870</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2019-02-24</th>\n",
       "      <td>-0.037503</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>-0.008886</td>\n",
       "      <td>-0.000277</td>\n",
       "      <td>-0.004443</td>\n",
       "      <td>0.001974</td>\n",
       "      <td>-0.007179</td>\n",
       "      <td>-0.015017</td>\n",
       "      <td>0.004975</td>\n",
       "      <td>0.040638</td>\n",
       "      <td>-0.005875</td>\n",
       "      <td>0.017988</td>\n",
       "      <td>0.028560</td>\n",
       "      <td>0.029752</td>\n",
       "      <td>-0.033539</td>\n",
       "      <td>-0.026249</td>\n",
       "      <td>0.004470</td>\n",
       "      <td>0.011015</td>\n",
       "      <td>-0.000403</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                 AMD  UBER  ZM        VZ       PFE         C      AAPL  \\\n",
       "Date                                                                     \n",
       "2019-01-27  0.088544   NaN NaN -0.061905  0.035230 -0.027578  0.026424   \n",
       "2019-02-03 -0.050317   NaN NaN -0.001748 -0.005908 -0.016821  0.037000   \n",
       "2019-02-10  0.012733   NaN NaN  0.007829 -0.010573  0.021847 -0.014540   \n",
       "2019-02-17  0.013680   NaN NaN  0.016871 -0.001829 -0.017059 -0.000073   \n",
       "2019-02-24 -0.037503   NaN NaN -0.008886 -0.000277 -0.004443  0.001974   \n",
       "\n",
       "                  FB       JPM      COST        GE       SYY      GOOG  \\\n",
       "Date                                                                     \n",
       "2019-01-27  0.082970 -0.024364 -0.023363  0.083342 -0.004111 -0.010991   \n",
       "2019-02-03  0.019027 -0.015008 -0.000065 -0.028041  0.050622 -0.004875   \n",
       "2019-02-10 -0.043464  0.026739  0.027374  0.013943  0.005643  0.002377   \n",
       "2019-02-17 -0.018790 -0.020247 -0.015868 -0.007107 -0.018145 -0.017981   \n",
       "2019-02-24 -0.007179 -0.015017  0.004975  0.040638 -0.005875  0.017988   \n",
       "\n",
       "                  UA      BABA       AAL       CCL      MSFT       WFC  \\\n",
       "Date                                                                     \n",
       "2019-01-27 -0.061427  0.025918  0.003201  0.010529 -0.070066 -0.044595   \n",
       "2019-02-03  0.018795  0.005619  0.008922 -0.009464  0.037369 -0.016511   \n",
       "2019-02-10 -0.014599 -0.021829 -0.040988 -0.003651  0.009532  0.018349   \n",
       "2019-02-17  0.017527  0.049785 -0.002482  0.021192  0.014754 -0.019099   \n",
       "2019-02-24  0.028560  0.029752 -0.033539 -0.026249  0.004470  0.011015   \n",
       "\n",
       "                   F  \n",
       "Date                  \n",
       "2019-01-27 -0.027758  \n",
       "2019-02-03 -0.028594  \n",
       "2019-02-10  0.003279  \n",
       "2019-02-17  0.004870  \n",
       "2019-02-24 -0.000403  "
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Resample by week.\n",
    "excess3 = excess_over_mean(data, resample_by='W', lag=True)\n",
    "excess3.head()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 432x288 with 1 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "s3 = pd.Series(excess3.iloc[:-1, :].values.flatten())\n",
    "ax3 = s3.plot.hist(bins=80)\n",
    "ax3.set_xlim(-0.4,0.4)\n",
    "ax3.set_xlabel('Return Over Mean')\n",
    "ax3.set_title('Distribution of Weekly Return Over Mean for 20 Stocks');"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       " 1.0    684\n",
       "-1.0    669\n",
       "dtype: int64"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "excess4 = excess_over_mean(data, binary=True,resample_by='W', lag=True)\n",
    "excess4.stack().value_counts()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "## Conclusion"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This notebook presents the method to label data according to excess return over mean. This method can return either numerical or categorical labels for observations. In this process:\n",
    " - Forward rates of return for assets are calculated for the entire selection of stocks indexed by time bars.\n",
    " - At each time index, the mean rate of return for all stocks is calculated. The mean is subtracted from each stock's return to find the excess return over mean.\n",
    " - If categorical labels are desired, the excess returns are converted to their signs.\n",
    "\n",
    "This method is useful in preventing unbalanced classes, which is likely to happen when labeling simply based on the sign of the return."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## References"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Coqueret, G. and Guida, T., 2020. Machine Learning For Factor Investing."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
